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Preface 


This book is designed to help you diagnose program failures in the Direct Access 
Device Space Management (DADSM) component. Before using this publication, 
you should have analyzed the program failure by following the diagnostic 
procedures in MVS/Extended Architecture DADSM and Common VTOC Access 
Facility Diagnosis Guide, LY26-3960. 


If after following these procedures no correction is found and if you must continue 


working on the problem, use this book to help you communicate with an IBM 
program specialist. The program specialist will further isolate the failure. 


Organization 
This publication has eight parts: 


e “Introduction” includes an overview of DADSM, a summary of its major 
functions, and a figure describing how these functions work together. 


e “Program Design and Organization” describes each DADSM function and 
subfunction, the interface to the controlling module, the system and DADSM 
data areas used, and a flowchart for each function or subfunction. These 
flowcharts contain brief module descriptions and the logic that determines the 
flow of control among DADSM routines. 


e “Module Directory” contains a cross-reference table to the DADSM object 
modules. 


e “Data Areas” briefly describes each significant DADSM data area and control 
block. 


e “Data Area Linkage” shows how the data areas are linked together. 


e Appendix A, “Data Area Layouts,” lists the offset, length, name, and field 
description of each significant data area. 


e Appendix B, “_DADSM Return Codes,” lists by function each DADSM return 
code and explains what these return codes mean. 


e “Abbreviations” defines the abbreviations used in this book. 
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Prerequisite Knowledge 


To use this book efficiently, you need to have already made a preliminary analysis 
of the program failure. The information you obtained from your analysis is the 
prerequisite knowledge for using this book. 


Required Publications 


You should be familiar with the information presented in MVS/Extended 
Architecture DADSM and Common VTOC Access Facility Diagnosis Guide, 
LY26-3960. This book explains how to analyze program failure. 


Related Publications 


Within the text, references are made to the publications listed in the table below: 


Order 
Short Title Publication Title Number 


DADSM and CVAF MVS/ Extended Architecture 
DADSM and Common VTOC 
Access Facility Diagnosis Guide 










LY26-3960 










Diagnosis Guide 





Data Facility Product: 
Customization 


MVS/Extended Architecture 
Data Facility Product Version 2: 
Customization 


DFDSS: Diagnosis Data Facility Data Set Services: SC26-3951 

Guide Diagnosis Guide 

JES2 Data Areas MVS/Extended Architecture LYB8-1191 
Data Areas (MVS/JES2) 

JES3 Data Areas MVS/Extended Architecture LYB8-1195 
Data Areas (MVS/JES3) 


Open/Close/EOV MVS/Extended Architecture LY26-3966 
Logic Open/Close/EOV Logic 


MVS/Extended Architecture 


GC26-4267 





GC28-1376 


System Messages 
GC28-1377 


Message Library: System 
Messages, Volumes 1 and 2 


VSAM Logic MVS/Extended Architecture LY26-3970 
VSAM Logic 





iv MVS/XA DADSM Diagnosis Reference LY26-3961-1 © Copyright IBM Corp. 1980, 1987 


Restricted Materials of IBM 
Licensed Materials — Property of IBM 


Summary of Changes 


| Release 3.0, June 1987 


| New Programming Support 

| The majority of DADSM code has been moved above 16Mb virtual, giving 

| approximately 100K bytes of virtual storage constraint relief. Linkage assist 
| modules have been added and load modules have been redefined. 


| DADSM functions continue to be supported for 24-bit addressing mode callers 
| without change. 


| Functions other than PROTECT now support 31-bit addressing mode callers and 
| their parameters above 16Mb virtual. 


| A new LSPACE macro has been added. This macro may be used to: 


| e¢ Define a parameter list for the SVC 78 (LSPACE) function which will support 
| 24-bit and 31-bit addressing mode callers. 


| e Request the existing LSPACE return message area. 
| ¢« Request the existing SMF functions. 


| e Request a new data return area format with additional volume-oriented 
| information. 


| ¢ Request the return of the format-4 DSCB’s data. 
| LSPACE diagnostic information has been improved. 


| The PARTREL macro has been modified to accept requests for ERASE (YES, 
| NO, or TEST) and TIOT (ENQ or NOENQ). 
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Release 1.0, April 1985 


New Programming Support 


The following features have been added to the DADSM component: 

¢ Anew PARTREL macro which will enable authorized users to effect a partial 
release of the space allocated to a data set without an associated 
OPEN/CLOSE. 

¢ A modified REALLOC macro which will: 
— Support all functions of the previous REALLOC macro. 
— Enable authorized users to cause the reallocation of a data set with as 

many as 16 absolute extents, and an optional Format 2 (ISAM) DSCB, on 


a given volume with an indexed VTOC. 


e SCRATCH will erase tracks for deleted data sets when requested by its caller 
or when a RACF-defined data set has the ERASE attribute. 


e Partial Release will erase tracks for space being released when the data set is 
RACF defined and has the ERASE attribute. 


Version 2 Publications 


The Preface includes the new order numbers for Version 2. A new REALLOC 
macro to enable users to reallocate data sets through the DADSM partial DSCB 
allocate function 
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Introduction 


This publication provides a summary of the major functions of the direct access 
device space management (DADSM) component, and a brief overview of its logic 
and organization. It introduces the descriptions of program activities that are 
found in the module prologs and as comments in the code, but it is not intended to 
replace those descriptions. In addition, this book is not intended to show you how 
to modify or repair the program logic. It will, however, give you an adequate basis 
for communicating with an IBM program specialist about possible program failures. 


If you do have a program failure, do NOT start your diagnosis of the problem by 
referring to this manual. You should begin diagnosis by following the instructions 
and procedures set forth in DADSM and CVAF Diagnosis Guide. 


Overview of DADSM 


The DADSM functions control allocation of space on direct access volumes 
through the volume table of contents (VTOC) of that volume. The VTOC is a 
data set consisting of a collection of data set control blocks (DSCBs) that describe 
the contents of a direct access storage device volume. There are seven types of 
DSCBs; each has a different purpose and is assigned a different name and format 
number. The VTOC and, optionally, the VTOC index, are built during volume 
initialization by Device Support Facilities, program number 5655-257. The VTOC 
and the VTOC index each reside in a single extent (that is, a contiguous data set). 
The VTOC’s address is located in the VOLVTOC field of the IBM-defined volume 
label. 


DADSM will use the common VTOC access facility (CVAF) macros to determine 
the VTOC format and to access an indexed VTOC. DADSM uses CVAF as well 
as channel programs to access a nonindexed VTOC. 

The VTOC may have a VTOC index. The VTOC index contains space maps that 
replace the format-5 DSCBs of the nonindexed VTOC and manage the VTOC and 
VTOC index space. The VTOC index contains an index of all the format-1 and 
format-4 DSCBs. 

The different types of DSCBs are: 

e Free DSCB: format-0 

e Identifter DSCB: format-1 


« Index DSCB (ISAM only): format-2 
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e Extension DSCB: format-3 

e VTOC DSCB: format-4 

e Free space DSCB: format-5 

e Shared extent DSCB: format-6 

Each DSCB in the VTOC corresponds either to a data set or data space currently 
residing on the volume, or to contiguous, unassigned tracks on the volume. DSCBs 
are the data set labels, which describe the characteristics of the data set or data 
spaces as well as the tracks on which the data sets reside. DSCBs for unassigned 
tracks indicate the location of unassigned, contiguous tracks. 


The functions performed by DADSM for controlling space allocation are: 


¢ Allocating space for new VIO data sets, non-ISAM data sets, and VSAM data 
spaces (NONIALL, subfunction of the ALLOC function) 


e Allocating space for new ISAM data sets (LALL, subfunction of the ALLOC 
function) 


e Allocating additional space for non-ISAM data sets and VSAM data spaces 
(EXTND function) 


e Rebuilding the format-5 chain and updating the format-4 
DSCB (CONV function) 


e« Deleting a data set or VSAM data space (SCRTCH function) 

e Freeing allocated but unused space (PRLSE function) 

e Renaming data sets (RNAME function) 

e Reading DSCBs (OBTN function) 

e Calculating available space on a direct access volume (LSPACE function) 
¢ Maintaining the system password data set (PRTCT function) 


e Recovering from interrupted indexed VTOC processing (VRF function) 


Allocating and Releasing Space on Direct Access Volumes 


The DADSM functions that allocate (ALLOC and EXTND) and release space 
(SCRTCH and PRLSE) also add, delete, and modify DSCBs of the VTOC. To 
make space available to a new data set or to increase the space allocated to a data 
set, the format-5 DSCBs or VTOC indexed space maps are searched for available 
space. The space is allocated to the data set by writing the description of the 
space, called an extent, to the data set’s DSCB and deleting the extent from the 
space available for allocation. To release space allocated to a data set, the allocate 
operation is reversed: The released extent is deleted from the data set’s DSCB and 
added to the existing space available for allocation. 
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Components of the operating system use the DADSM functions to allocate and 
release space in response to data definition (DD) statements. For example, the job 
management (scheduler) routines call the ALLOC function to obtain space for a 
new data set. 


VTOC-Related Service Functions 


RNAME, OBTN, LSPACE, and PRTCT functions are used to read and change 
control information on the VTOC; they neither allocate nor release space. System 
macro instructions can be used to invoke these functions. 


Volume Table of Contents Integrity 


In an operating system with only one processor, two or more tasks may attempt to 
access the same VTOC simultaneously for the purpose of reading or updating (that 
is, adding, deleting, or modifying DSCBs) that VTOC. If more than one processor 
has access to the same device or devices, they may attempt to access the VTOC 
simultaneously. 


To be sure that a VTOC is not changed while the DADSM functions are in 
process, the DADSM functions issue RESERVE, ENQ, and DEQ macro 
instructions. These macro instructions provide or release exclusive control of the 
VTOC for the task issuing the macro instruction. The RESERVE macro 
instruction is needed for systems in which two or more processors are processing 
concurrently, using the same data sets. These macro instructions provide exclusive 
control of the VTOC for the task issuing the macro instruction. Depending on the 
macro instruction, the “‘set-must-complete” option or the “‘release-must-complete” 
option may be specified in an operand of the macro instruction. The ALLOC, 
EXTND, SCRTCH, RNAME, PRLSE, LSPACE, and PRTCT functions of 
DADSM issue these macro instructions. Of these routines, only ALLOC, 
SCRTCH and PRLSE, use SMC=STEP in the ENQ and RESERVE macros, and 
RMC=STEP in the DEQ macro. The EXTND function links to the status routine 
(rather than issuing the ENQ macro) to obtain “step-must-complete” status, if the 
task that called EXTND has not already done so. 


The integrated catalog facility/virtual storage access method (integrated catalog 
facility/ VSAM) catalog management routines modify the DS4AMCAT and 
DS4AMTIM fields of the VTOC (format-4) DSCB. These routines also issue the 
RESERVE, ENQ, and DEQ macro instructions to maintain exclusive control while 
making modifications. 


Note: When operating in an environment in which direct access storage devices 
are not shared among systems, the RESERVE macro instruction defaults to (acts 
as) an ENQ macro instruction. 


Interrupted VTOC-Update Functions 


If a system fails or a permanent I/O error occurs during allocation of space or 
during a routine that updates the VTOC, the VTOC will probably be in error. To 
make sure the error is recorded, the DADSM functions use the DADSM 
interrupt-recording facility (DIRF) when a nonindexed VTOC is being accessed. If 
the VTOC is an indexed VTOC, the VTOC recording facility (VRF) is used to 
record and recover from interrupted VTOC-update functions. 
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DADSM Interrupt Recording Facility (DIRF): DIRF processing is applicable only to 
nonindexed VTOCs and involves turning on a bit in the VTOC at entry to the 
DADSM function, and, if no I/O errors occur during DADSM processing, turning 
it off again at exit from that function. 


This bit is called the DIRF bit and is bit 5 of the DS4VTOCI field of the format-4 
DSCB. The SCRTCH and PRLSE functions also turn on the DIRF bit if they 
encounter overlapping extents in a format-5 DSCB. 


When a volume has been transported from a Disk Operating System (DOS), it will 
have the DOS bit on (bit 0 of the DS4VTOCI field of the format-4 DSCB). 


The next time an attempt is made to allocate space on a volume that has either the 
DOS bit or the DIRF bit set, the VTOC conversion routine (CONV) is invoked by 
the ALLOC or EXTND functions, whichever is attempting to allocate more space 
on the volume. The CONV function builds new format-5 DSCBs to represent the 
available space on the volume, updates the format-4 DSCB, and returns to ALLOC 
or EXTND to continue the allocation. 


VIOC Recording Facility (VRF): RF processing is applicable only to indexed 
VTOCs and records more functionally related data than DIRF. The additional 
data allows VRF processing to correct a specific problem rather than rebuilding the 
VTOC each time DADSM is interrupted. VRF is invoked by the ALLOC, 
SCRTCH, EXTND, PRLSE, and RNAME functions. 


The ALLOC, EXTND, SCRTCH, PRLSE, and RNAME functions call pre- and 
postprocessing installation exits. These exits, IGGPREOO and IGGPOSTO, allow 
your installation to control DASD space or reject requests based on installation 
criteria. 


For more information on installation exits, see Data Facility Product: Customization. 


DADSM provides seven linkage assist routines. IGGO553A is the linkage assist 
routine for the EXTND function. IGG0553A allows callers in 24-bit addressing 
mode to branch to the EXTND module, IGG05530. Callers in 31-bit addressing 
mode may call IGG05530 directly. 


IGGPEXIT is the linkage assist routine for the installation exit modules 
IGGPREO0 and IGGPOST0. IGGPEXIT is used to branch to an installation exit 
module when that module is in 24-bit addressing mode. If the module is in 
31-addressing mode, control passes directly to the installation exit. 


The remaining five linkage assist routines are used with installation replaceable 
modules in the SCRTCH and RNAME functions. These linkage assist routines are 
always called, regardless of whether the caller is in 24- or 31-bit addressing. 
IGGDAS00, IGC0002I, and IGGO29DN are used with the SCRTCH function. 
IGGDAR0O0 and IGC00030 are used with the RNAME function. 
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DADSM Recovery Routines 


To avert a complete system failure when an abnormal termination condition arises 
in DADSM processing, the DADSM functions include a recovery function. This 
function is given control by the recovery/termination manager (R/TM) when an 
abnormal termination condition is encountered ina DADSM routine. The same 
recovery routine is given control when an open, close, or EOV routine encounters 
an abnormal termination condition; the DADSM recovery function is therefore 
documented in Open/Close/EOV Logic. 


During the initialization of each DADSM function, the address of the recovery 
routine is established when virtual storage is obtained by the DADSM function. 
The O/C/EOV-DADSM recovery routine load module name is IFGORROA. Its 
address is established for a DADSM routine when the IECRES GET macro is 
issued for a work area. The functions of the IECRES macro, the expansion of 
which results in a branch to the O/C/EOV-DADSM service routine, IFGO19RA, 
are also documented in Open/Close/EOV Logic. 


The DADSM recovery routine saves diagnostic information in the SYS1.LOGREC, 
SYS1.DUMP, and GTF data sets, and then releases any resources obtained by the 
DADSM function before it failed. 


Functions of DADSM 


ALLOC Function 


Figure 1 on page 9 summarizes the major functions in DADSM. In this section, 
each of these functions is described in terms of its external processing environment. 
For each function, the following information is provided: 


e Description: a brief description of the function 
e Results: the processing results produced by the function 


e Calling components: where applicable, the system components that can 
transmit requests to the function 


In the following discussion, note that each function is identified by a function 
name. This name is the same as the keyword name used to identify the function in 
DADSM and CVAF Diagnosis Guide. All functions return to the caller when the 
requests are fulfilled. 


Description Processes requests to allocate space on a direct access 
storage device. The ALLOC function is invoked by an 
SVC 32. 

Results Updated VTOC index and/or VTOC reflecting the new 


contents and space available on the volume. Return 
code in register 15. 
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Calling Components 


EXTND Function 


Description 


Results 


Calling Components 


SCRTCH Function 


Description 


Results 


Calling Components 


PRLSE Function 


Description 


Results 
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Scheduler, utilities, integrated catalog facility and 
VSAM catalog management, REALLOC macro, and 
any other caller of SVC 32. 


Allocates additional space (extents) to sequential data 
sets or VSAM data spaces. EXTND is invoked when a 
data set requires more space than is currently allocated. 
EXTND can also process VSAM requests that do not 
include a data extent block (DEB) parameter. 


Updated VTOC index and/or VTOC reflecting the new 
contents and space available on the volume. The return 
code is in register 13. 


EOV, integrated catalog facility and VSAM catalog 
management, OS catalog management. 


Deletes data sets and VSAM data spaces. Optionally, 
erases DASD tracks before releasing space. The 
SCRTCH function is invoked by the SCRATCH macro 
instruction (SVC 29). 


Updated VTOC index and/or VTOC. The return code 
is in register 15. Scratch status code is in volume list. If 
erase processing is performed, residual user data is made 
unreadable. 


Integrated catalog facility and VSAM catalog 
management, MSS, scheduler, utilities, or problem 
program. 


Releases unused space, and extents, allocated to a 
sequential or partitioned data set. Optionally, erases 
DASD tracks before releasing space. The PRLSE 
function may be invoked by a close issued for a data set 
for which a release has been specified in the DD card, or 
a restart from a checkpoint where a data set has been 
extended after the checkpoint, or an authorized user of 
the PARTREL macro. 


Updated VTOC index and/or VTOC. The return code 


for a close or checkpoint/restart caller is in register 1. 
The return code for a PARTREL caller is in register 15. 
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RNAME Function 


Description 


Results 


Calling Components 


OBTN Function 


Description 


Results 


Calling Components 


LSPACE Function 


Description 


Results 


Calling Components 
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Finds the DSCB for a specified data set or VSAM data 
space and changes its name. The RNAME function is _ 
invoked by the RENAME macro instruction (SVC 30). 


The updated VTOC index and/or VTOC with the new 
data set or VSAM data space name (after verifying that 
the requested name does not duplicate one already on 
the volume). The rename status code is in volume list. 
The return code is in register 15. 


HSM, utilities, or problem program. 


Reads a specified DSCB from the VTOC of a specified 
volume into the caller’s work area; for suballocated 
VSAM data sets, obtains equivalent information from 
the appropriate VSAM catalog. The OBTN function is 
invoked by the OBTAIN macro instruction (SVC 27). 


The requested information.is put in the caller’s work 
area. The return code is in register 15. 


System components, problem program, and utilities. 


Calculates the amount of free space on a given direct 
access volume. When called with a parameter list, 
LSPACE can calculate the fragmentation index, and 
report on the number of format-O DSCBs and free 
VIRs. LSPACE returns this information in a data 
(rather than a message) format. The LSPACE function 
is invoked by an SVC 78. 


A type-19 record is written to the SMF data set, if SMF 
is requested and is active on the system. If the 
MONITOR SPACE command was issued, space 
information is moved to the message area provided by 
the caller. The message or parameter list address is in 
register 1. The reason code is in register 0; the return 
code is in register 15. 


LSPACE macro, MSS, O/C/EOV, scheduler, SMF, 
problem program, and utilities. 
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PRTCT Function 


Description 


Results 


Calling Components 


VRF Function 


Description 


Results 


Calling Components 
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Maintains the system password data set, which controls 
access to data sets and associated control information. 
The PRTCT function is invoked by the PROTECT 
macro instruction (SVC 98). 


For add, replace, and delete operations, the password 
data set is updated. For list operations, the caller’s 
80-byte buffer contains the requested record. The 
return code is in register 15. 


Utilities, problem program. 


Accesses recovery data and corrects the VTOC and 
VTOC index to an executable state after an interrupted 
VTOC update: indexed VTOC only. The condition that 
causes invocation of the VRF function is any function 
that detects active VRF data in the VTOC index. 


The recovery of interrupted update processing or the 
VTOC index is disabled. The return code is in register 
15. 


DADSM, DFDSS. 
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Program Design and Organization 


ALLOC Function 


INIT Subfunction 


In this section, the following information is provided for each function of DADSM: 
e Description: a brief description of the function 


e Interface to Controlling Module: the interface to the module that controls or 
oversees processing within the function 


e System and DADSM Data Areas Used: the names of the data areas used by 
the function (or subfunction) 


e Program Organization: charts showing the module-to-module flow 


The allocate routines find unused space on direct access storage volumes and make 
that space available for new data sets. They receive control through an SVC 32. 
These routines create a format-1 data set control block (DSCB) for each new data 
set, and, in the format-1 DSCB, write descriptions of the direct access storage areas 
(these description are called extents). Available extents are obtained by searching 
the format-5 DSCBs on the VTOC (for a nonindexed VTOC) or the volume pack 
space map (VPSM) of the VTOC index. The allocate routines are divided into 
four subfunctions and are described below. 


Description 


The INIT subfunction verifies that space requests are properly made, performs 
space allocation for VIO data sets by building the virtual DSCB (VDSCB), 
prepares for non-VIO data set allocation, takes the preprocessing exit, and 
determines whether there is an indexed VTOC on the volume. If a REALLOC 
ALLOC=ABS request is made for a volume without indexed VTOC support, the 
request will fail. 


Interface to Controlling Module 


If register 1 has the high—order bit on, the complement of register 1 is the address 
of the REALLOC caller’s parameter list. 


For callers other than REALLOC, register 0 points to the job file control block 
(JFCB); however, if register 0 has the high-order bit on, register 0 points to a 
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partial DSCB. Register 1 points to the unit control block (UCB) for the device on 
which the data set is to be located or, if a VIO data set is being allocated, register 1 
points to a device code. Register 2 points to a variable-length list of DSAB 
addresses if an ISAM data set is being allocated. 
System Data Areas Used 

Allocate work area 
DADSM Data Areas Used 

Buffer list 

CVAF extent table 

CVAF parameter list 

DADSM extent table 

DADSM preprocessing and postprocessing installation exit parameter list 

Partial data set control block (PDSCB). 

Data set control blocks (DSCB) 

REALLOC parameter list 

System Authorization Facility (SAF) work area and parameter list 

Transfer control table 

VTOC recording facility data 

WTG table 
Program Organization 


See Figure 2 on page 13. 
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NONIALL Subfunction 
Description 


The NONIALL subfunction converts the space requested for a data set or VSAM 
data space to the equivalent number of tracks, determines the type of allocation 
request, allocates space, and (for an indexed VTOC) adds a new entry to the index. 
NONIALL receives control from the INIT subfunction and allocates space for 
non-ISAM data sets: 


e Calls SAF to verify access authority via RACF generic or discrete profile. 
Defines a discrete profile if the caller has requested it. 


e If user labels are requested, a user-label track is allocated from the VPSM for 
an indexed VTOC or format-5 DSCBs for a nonindexed VTOC. 


e« Absolute-track allocation requests for nonindexed VTOCs locate the extent 
containing the specified track in the format-5 DSCB for a nonindexed VTOC 
or the VPSM for an indexed VTOC. 


e For cylinder or track allocation requests, the extents required to fill the request 
are located through the format-5 DSCB for a nonindexed VTOC or the VPSM 
for an indexed VTOC. 


e When space is needed on a volume, the VTOC is checked for enough 
contiguous tracks; the request is filled, using as many as five noncontiguous 
groups of free tracks. The appropriate DSCBs and VTOC index records are 
modified to reflect the assignment of the tracks. 


e The data set name is added to the index for an indexed VTOC. 

e Format-1 and format-3 DSCBs are built, if required. 

e The VTOC index space maps are updated. 

e The format-4 and format-5 DSCBs are updated for a nonindexed VTOC. 


e IfaREALLOC ALLOC=MOV request is made (high-order bit is on in 
register 1 upon entry to the INIT subfunction and the parameter list indicates 
ALLOC=MOV) space will be filled in as many as 16 noncontiguous groups of 
free. tracks for any data set not cataloged in an integrated catalog facility 
catalog, and as many as 123 noncontiguous groups of free tracks for any 
VSAM data set cataloged in an integrated catalog facility catalog. Optionally, 
the groups will be a minimum number of tracks as specified in the parameter 
list passed from the caller. 
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If aREALLOC ALLOC=ABS request is made (high-order bit is on in register 


1 upon entry to the INIT subfunction and the parameter list indicates 


ALLOC=ABS) the specified volume’s indexed VTOC support will be used in 


allocating the absolute extents requested by the caller’s format 1, and 


(optional) format-3 DSCB parameters. The VTOC and VTOC index records 


will be updated using the caller’s format 1, optional format 2, and optional 


format-3 DSCB specifications. 


Interface to Controlling Module 


Register 11 points to the job file control block (JFCB); however, if register 11 has 


its high-order bit on, register 11 points to the partial DSCB (full format-1 DSCB 


for REALLOC ALLOC=ABS). Register 13 points to the allocate work area. 


System Data Areas Used 


Allocate work area 


DADSM Data Areas Used 


Buffer list 

CVAF extent table 

CVAF parameter list 

DADSM extent table 

DADSM preprocessing and postprocessing installation exit parameter list 
Partial data set control block (PDSCB). 
Data set control blocks (DSCB) 
REALLOC parameter list 

SAF work area and parameter list 
Transfer control table 

VTOC recording facility data 


WTG table 


Program Organization 


See Figure 3 on page 16. 


LY26-3961-1 © Copyright IBM Corp. 1980, 1987 Program Design and Organization 


15 





From 
1GG0325A 
INIT 


Nonindexed 


Restricted Materials of IBM 


Licensed Materials — Property of IBM 


START 


1GG0325B8 


Requests conversion and 
type determination; 


processes ali type requests 
for an indexed VTOC 





























VTOC Nonindexed Indexed VTOC Nonindexed 
absolute vToc or (non- vToc 
ra nonzero indexed Error From user label 
quantity VTOC- IGGO325A 
zero INIT 
1GGO0325C 1GG0325D IGGO325E quantity) IGG0325H 1GG0326K 
Updates format-4 
Pp Builds f “1 DSCB and handles 
babieiual Searches for Eee aie errors; dequeues Allocates user 
absolute fracanace and format-3 VTOC: jack 
tracks p DSCBs the VTOC; goes to abel extent 
postexit; frees all 
work areas 
Indexed Ze 
Error Error] VTOC Nonzero ence 
or Error Space Error 
Nonindexed Altocation Alloca- 
G@)G) @)@ @ |™ \ 
IGG0325G & (2) (2) 
Updates format-5 
DSCBs 
Error 
Partitioned Gata set 
if E CVAF 
IGGPREOO des Error 
called IGGOBSSE > Encountered 
previously (EXTND) 
1GGO20P3 tGG032DB From 1GGOCLF2 
PRLSE 1GG03251 
1GG0290D SCRTCH issues SDUMP for INIT 
1GG03217 [ALL j 
DADSM functions Foemaa the 
1GG03001 RNAME that receive an BPAM direct 
To CeUaCSL Ae as unexpected CVAF ven 
return code 
pha IGGVRFO1 VAF 


IGGVRFO2 VRF 
IGGVRFO3 VRF 
IGGVRFO4 VRF 
IGGVRFOS VRF 


Note: ‘Return to caller’’ means return 
to caller of the function. 


Return to Calling 
module via BR 14 Return to Caller 
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[ALL Subfunction 


Description 


The IALL subfunction receives control from the INIT subfunction and allocates 
space for 


« ISAM data sets. 


« Finding available space on the volume by searching the format-5 DSCBs on 
the VTOC or the VPSM (for an indexed VTOC) in the VTOC index and 
building an extent table of the available space. 


e When space is needed on a volume, the VTOC is checked for enough 
contiguous, available tracks to satisfy the request. If there are not enough 
contiguous tracks, the request is filled, using as many as five noncontiguous 


groups of free tracks. The appropriate DSCBs and VTOC index records are 


modified to reflect the assignment of the tracks. 
e Adding a new DSN entry to the VTOC index (for an indexed VTOC). 
e Building format-1, format+2, and format-3 DSCBs. 
e Updating format-4 and format-5 DSCBs (for a nonindexed VTOC). 


e Updating the VTOC index (for an indexed VTOC). 


If an ISAM data set is to be allocated on more than one volume, multivolume data 
set initialization is performed and IALL processing begins again. IALL calls SAF 
to verify authority via RACF generic or discrete profile and adds the new volume 


to the existing discrete profile when requested by the caller. 


Interface to Controlling Module 


Register 11 points to the job file control block (JFCB). Register 13 points to the 


allocate work area. 
System Data Areas Used 
Allocate work area 
DADSM Data Areas Used 
Buffer list 
CVAF extent table 
CVAF parameter list 
DADSM extent table 
DADSM preprocessing and postprocessing installation exit parameter list 


Data set control blocks (DSCB) 
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SAF work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 


See Figure 4 on page 19. 
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CONV Subfunction (For Nonindexed VTOCs Only) 
Description 


The CONV subfunction receives control from the ALLOC INIT subfunction or the 
EXTND function if one of the following conditions is met: 


¢ The volume has been processed under the DOS operating system leaving the 
DOS bit (DSDOSBT in field DS4VTOCI) on in the format-4 DSCB. 


e The volume previously contained an indexed VTOC, but the VTOC index was 
disabled, leaving the DOS bit on in the format-4 DSCB. 


e A permanent I/O error or system failure during DADSM processing occurred, 
leaving the DIRF bit (DSDIRF in field DS4VTOCI) on in the format-4 DSCB. 


The procedure to reclaim and convert VTOCs involves: 


e Rebuilding the format-5 DSCBs by removing format-1 and format-3 extents 
from total volume space. 


e Writing format-5 DSCBs to the VTOC. 

e Rebuilding the format-6 DSCBs from the format-1 DSCBs. 
e Updating the format-4 DSCB. 

Interface to Controlling Module 


Register 7 points to the UCB for the volume whose VTOC is to be converted. 
Register 13 points to the allocate work area. 


System Data Areas Used 
Allocate work area 
DADSM Data Areas Used 
Data set control blocks (DSCB) 
Transfer control table 
WTG table 
Program Organization 


See Figure 5 on page 23. 
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Deactivating Automatic VTOC Reclamation 


There are situations in which you may not want to automatically convert or reclaim 
a VTOC that has the DIRF bit set in the format-4 DSCB. By applying a superzap, 
or in-storage, alteration to IGG0325Z, you can prevent the VTOC from being 
automatically reclaimed. The job control language and control statements for 
altering IGG0325Z follow: 


//STEPO1 EXEC PGM=AMASPZAP 
//SYSLIB DD DSN=SYS1.LPALIB,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

NAME IGG0325Z IGG0325Z 

VER 0000 0700 

REP 0000 0701 
/* 
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Description 


The EXTND function initializes extension of data set allocation and proceeds as 
follows: 


Calculates the last track written to the data set when an extension is to be 
made of the current volume and determines whether the secondary space 
request can be filled by the tracks following the last allocated track. 


Searches format-5 DSCBs or the VPSM (for an indexed VTOC) for free 
extents and builds an extent table. 


When space is needed on a volume, the VTOC is checked for enough 
contiguous, available tracks to satisfy the request. If there are not enough 
contiguous tracks, the request is filled, using as many as five noncontiguous 
groups of free tracks. The appropriate DSCBs and VTOC index records are 
modified to reflect the assignment of tracks. 


Builds and/or updates the appropriate format-1 and format-3 DSCBs. 

Adds the DSN to the VTOC index if the extension is to a new volume. 
When extending onto a new volume, calls SAF to verify authority via RACF 
generic or discrete profile. In the case of a discrete profile, adds the new 


volume to the existing discrete profile. 


Updates the appropriate format-4 and format-5 DSCBs (for a nonindexed 
VTOC only). 


Updates the VTOC index. 


Note: Data sets with indexed sequential organization or data sets beginning with 
“SYS1.VTOCIX” cannot be extended. 


EXTND can process VSAM requests that do not include a DEB parameter. 


Interface to Controlling Module 


Register 4 points to the O/C/EOV work area. Register 5 points to the data extent 
block (DEB) of the data set to be extended. Register 10 points to the UCB for the 
volume. Register 13 contains the extend code. 
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System Data Areas Used 
Extend work area 
DADSM Data Areas Used 
Buffer list 
CVAF extent table 
CVAF parameter list 
DADSM extent table 
DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 
SAF work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 


See Figure 6 on page 26. 
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SCRTCH Function 
Description 
For each volume, the SCRTCH function does the following: 
e Determines whether a volume containing the data to be scratched is mounted 
on a unit allocated to the job. If the volume is not mounted, SCRTCH 


requests that the required volume be mounted. 


¢ Reads in format-4 (for nonindexed VTOCs only) and format-1 DSCBs for the 
data set to be scratched. 


e Calls SAF to verify authority via RACF generic and/or discrete profiles. A 
discrete profile will be deleted. 


e Calls SAF to determine via RACF whether data set erasure is to be performed 
when the caller of SCRTCH does not explicitly specify such action. 


e If required, makes all DASD tracks allocated to the data set unreadable before 
removing DSCBs. 


e Removes the format-1, format-2, and format-3 DSCBs for data sets being 
scratched. 


e For MSS virtual volumes, relinquishes space. 
e Deletes the data set name from the VTOC index. 


e Updates (for a nonindexed VTOC) the format-4, format-S, and (for 
split-cylinder data sets) format-6 DSCBs. 


e Updates the VPSM (for an indexed VTOC). 
Interface to Controlling Module 


Register 0 contains all zeros or points to the UCB for the device that can be used 
to mount volumes. Register 1 points to the scratch parameter list. 


System Data Areas Used 
Scratch work area 


Second scratch work area 
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DADSM Data Areas Used 
Acquire/Relinquish parameter list 
Buffer list 
CVAF extent table 
CVAF parameter list 
DADSM extent table 
DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 
SAF work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 


See Figure 7 on page 29. 
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PRLSE Function 


Description 


The PRLSE function deletes unused space, and extents, allocated to sequential or 
partitioned data sets as follows: 


e Calls SAF to determine via RACF whether erasure is to be performed for 
released tracks when the caller of PRLSE does not explictly specify such 
action. 


e Reads in the format-4 DSCB, and processes the DIRF for a nonindexed 
VTOC, or VRF for an indexed VTOC 


e If required, invokes the DADSM track erase module (IGG029ER) to make 
released tracks unreadable 


e Updates the format-1 DSCB 

e Updates or removes the format-3 DSCB 

e Writes back the format-1 and format-3 DSCBs 

e For MSS virtual volumes, relinquishes space 

e« Updates the format-4 and format-5 DSCBs (for a nonindexed VTOC) 
e Updates the VPSM (for an indexed VTOC) 

Interface to Controlling Module (IGG020P0) 


Register 1 points to the PARTREL parameter list. Register 13 points to a standard 
register save area. Register 14 provides the desired return address. 


Interface to Controlling Module (IGG020P1) 


If register 2 contains zero, entry was made from IGGO20P0. Register 3 points to a 
partial data control block (DCB) which points to an area for the construction of a 
dummy DEB. Register 4 points to a partially initialized O/C/EOV work area. 
Register 10 points to the UCB of the data set whose space allocation is to be 
reduced. Register 13 points to the partial release work area (the data set name is 
passed within this area). 


For callers other than IGGO20P0, register 2 points to the DCB for the data set 
whose space allocation is to be reduced. Register 4 points to the O/C/EOV work 
area. Register 7 points to the restart work area if entry is from restart. Register 10 
points to the UCB of the data set whose space allocation is to be reduced. 
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System Data Areas Used 
Partial release work area 
DADSM Data Areas Used 
Acquire/Relinquish parameter list 
Buffer list 
CVAF extent table 
CVAF parameter list 
DADSM extent table 
DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 
PARTREL parameter list 
PARTREL partial release work area 
SAF work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 


See Figure 8 on page 33. 
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PRTICT Function 
Description 
The PRTCT function: 


e Reads a format-1 DSCB for the PASSWORD data set from the system volume 
e Adds, replaces, deletes, or lists entries in the system PASSWORD data set 
e Updates the format-1 DSCB 
Note: VSAM data spaces are protected using another method. See VSAM Logic. 
Interface to Controlling Module 
Register 1 points to the protect parameter list. 
System Data Areas Used 
Not applicable 
DADSM Data Areas Used 
Data set control blocks (DSCB) 
Protect work area 
Program Organization 


See Figure 9 on page 35. 
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RNAME Function 
Description 
The RNAME function: 


e« Determines whether the volume is mounted on a unit allocated to the job; if 
not, RNAME requests that the required volume be mounted. 


e Calls SAF to verify authority via RACF generic or discrete profiles. Renames 
the discrete profile when one exists. 


e Deletes the old data set name from the VTOC index and adds the new data set 
name to the VTOC index (for an indexed VTOC only). 


e Updates the format-1 DSCB with the new data set or VSAM data space name. 
e Writes a type-18 SMF record, if necessary. 

e Processes additional volumes. 

Interface to Controlling Module 


Register 0 contains all zeros or points to the UCB of the device that can be used to 
mount volumes. Register 1 points to the rename parameter list. 


System Data Areas Used 
Not applicable 
DADSM Data Areas Used 
Buffer list 
CVAF extent table 
CVAF parameter list 
DADSM extent table 
DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 
Rename work area 


SAF work area and parameter list 
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Second rename work area 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 


See Figure 10 on page 38. 


LY26-3961-1 © Copyright IBM Corp. 1980, 1987 


Program Design and Organization 37 


START 


iGGDAROO 


Parameter list 
copy. 


IGGO30DU 


Entry point dummy 


module 





'GC00030 


From 

IGGO290F 

(alias tGGO300F) 
SCRTCH 


a. Volume mounted 


Linkage assist 


IGGDARO3 


Initializes RNAME 


function 





1GG03002 






Determines whether 
volume is mounted 










Volume 
is to be 
mounted 







called 
previously 









To 
IGGPOSTO INIT 










Volume is to 
be demounted 





Return to Caller 


To IGGO2S0F 
(alias IGGO300F) 
SCRTCH 


Rename 


Figure 10. 


Error 


Return to Caller 


Required volume is mounted 







it 
1GGPREOO 'GG03001 


Updates RACF 
profile; updates 


Restricted Materials of IBM 
Licensed Materials — Property of IBM 





Utilities, problem program 


From 
1GGO2S0F 

(alias IGGO300F) 
Volume 


demounted 44 


AFT] PHA™P™27zZ2Z#=7};' From SECLOADA 











IGGVRFOO 
VAF 


format-1 DSCB 
~ 
S If data set 
SS password 
~ 
= protected 
S To 
SECLOADA 
SSS (O/C/EOV) to 
verify password 
More 
volumes © 
Preexit To 
IGGPREOO 
INIT 
Active 
VRF data — To 


Note: “Return to caller’ means 
return to caller of the 
function. 





38 MVS/XA DADSM Diagnosis Reference 


LY26-3961-1 © Copyright IBM Corp. 1980, 1987 


Restricted Materials of IBM 
Licensed Materials — Property of IBM 


OBTN Function 

Description 

The OBTN function: 
Reads one DSCB into the caller’s work area, which contains either: (1) the 
96-byte data portion of the format-1 DSCB (or format-4 if the data set name 
is 44 characters of X'04' of the named data set, along with its absolute track 
address (CCHHR); or (2) the 140-byte DSCB whose absolute track address is 
supplied; or (3) for VIO data sets, the virtual DSCB. 

Interface to Controlling Module 

Register 1 points to the obtain parameter list. 

System Data Areas Used 
Not applicable 

DADSM Data Areas Used 
Buffer list 
CVAF parameter list 
DADSM preprocessing and pestprocessing installation exit parameter list 
Data set control blocks (DSCB) 
Obtain work area 
Transfer control table 
WTG table 

Program Organization 


See Figure 11 on page 40. 
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LSPACE Function 


Description 
The LSPACE function: 


e« Calculates the unallocated volume space from format-5 DSCBs (for a 
nonindexed VTOC) or the VPSM (for an indexed VTOC). 


| e Optionally calculates the fragmentation index. 
| « Optionally reports the number of format-0 DSCBs and free VIRs. 
| « Optionally returns the format-4 DSCB. 


e If SMF information is required, the volume label is read in and a type-19 
record is constructed and written to the SMF data set. 


e If the MONITOR SPACE command is in effect, space information is placed in 
the caller’s message area. 


Interface to Controlling Module 
Register 0 points to the UCB of the device on which the volume is (or can be) 
mounted. Register 1 contains the SMF code in the high-order byte and points to 
the message area in the three low-order bytes. 
System Data Areas Used 
Not applicable 
DADSM Data Areas Used 
Buffer list 
CVAF parameter list 
DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 
LSPACE work area 
Transfer control table 
WTG table 
Program Organization 


See Figure 12 on page 42. 
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VRF Function 


Description 

The VRF function: 

e Reads VRF data from the the VTOC index map (VIXM). 

e Uses the function code (VRFCODE) in the VRF data to determine the VRF 
recovery routine which is invoked to recover the interrupted function (for 
example, function code X'03' will cause VRF recovery routine, IGGVRFO3, 
to be given control). 


e Zeros out VRF data when the updates are completed. 


Note: IGGVRFOO0 through IGGURFO05 are DADSM modules. IGGVRF06 is a 
DFDSS module. See DFDSS: Diagnosis Guide. 


Interface to Controlling Module 
Register 1 contains the UCB address. Register 13 contains the pointer to an 
18-word register save area. The save area must be acquired with the IECRES 
macro. 
System Data Areas Used 
Not applicable 
DADSM Data Areas Used 
Buffer list 
CVAF extent table 
CVAF parameter list 
Data set control blocks (DSCB) 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 


See Figure 13 on page 44. 
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Module Directory 


The section contains a table that lists each executable object module in DADSM, 
the function and subfunction to which the module belongs, and the figure number 
of the module flowchart in which reference to the object module can be found. 
The figure numbers in boldface indicate where the module is described in detail. 


The majority of DADSM modules reside above 16Mb virtual. The remaining 
modules fall into two categories: modules that always reside below 16Mb virtual, 
IGGPEXIT, IGG19EK, and IGG553A, and the installation replaceable modules 
which may or may not reside above 16Mb virtual depending on how they are 
coded. These modules are identified by a footnote in the table below. 


Figure No. (and Part No., 
Subfunction if applicable) 


1GC0002G_~—| OBTN Mo) 
IGCooo2 ~—_—| SCRTCH 
IGC0003B_~—| ALLOC el Ld 
IGC0007H_~~—*| LSPACE Wo 
IGCOO09H =| PRTCT 9 
IGCO107H_~—«| LSPACE WZ 
IGCO109H__—| PRTCT 9 
IGC0209H_—«| PRTCT 9 
iGODARI: ae 
IGGDASOO! | SCRTCH 
IGGDASO3_| SCRTCH 
IGGDATBL?_ | COMMON te ed 





1 This module may reside above or below 16Mb virtual. 


2 This module is shared by more than one function. 
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Figure No. (and Part No., 
if applicable) 
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Figure No. (and Part No., 
Function Subfunction if applicable) 
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Data Areas 


System Data Areas 


Allocate Work Area 


Extend Work Area 


The following data areas and control blocks used by the DADSM functions can be 
found in Data Areas, available only in microfiche. 


Mapped by: TECALLWA nhacro. 

Chained from: Register 13 when the allocate (ALLOC) function is in control. 
Storage Location: Subpool 230. 

Description: Work area used by ALLOC to perform its function. 


Created when: During the allocate initialization subfunction (INIT) by module 
IGCO003B. 


Released when: When the ALLOC function exits, IGG0325H frees it. 
IGG032I17 frees it if the allocation was an ISAM data set. 
IGG0325I frees it if the allocation was a VIO data set. 


IGGOCLF2 frees it if the allocation was a partitioned data set or a CVOL. 


Mapped by: TECEXTWA macro. 
Chained from: Register 11. 
Storage Location: Subpool 230. 


Description: Used by the extend (EXTND) function to contain control blocks for 
extending the data set. 


Created when: By module IGG05530 during extend initialization (EXTND). 


Released when: By module IGGOS53E when the EXTND function is finished. 
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Mapped by: TECPRLWA macro. 


Chained from: Register 11 or 13 while the partial release function (PRLSE) is in 
control. 


Storage Location: Subpool 230. 
Description: Used by partial release (PRLSE) to perform its function. 


Created when: The PRLSE function initializes. IGGO20P0 creates it for the 
PARTREL caller. IGGO20P1 creates it for the close or checkpoint/restart caller. 


Released when: The PRLSE function exits. IGGO20P0 frees it for the PARTREL 
caller. IGGO20P3 frees it for the close or checkpoint/restart caller. 


Mapped by: IECSCRWA macro. 

Chained from: Register 13 while the scratch function (SCRTCH) is in control. 
Storage Location: Subpool 230. 

Description: Used by scratch (SCRTCH) to perform its function. 

Created when: By module IGGDAS0O3 during scratch initialization (SCRTCH). 


Released when: By module IGGO290D when SCRTCH finished. 


Mapped by: IECSCRWA macro. 

Chained from: SECWAPTR in IECSCRWA. 

Storage Location: Subpool 230. 

Description: Used by scratch (SCRTCH) to perform its function. 
Created when: During SCRTCH initialization by module IGGDASO3. 


Released when: SCRTCH is finished by module IGGO290D. 


50 MVS/XA DADSM Diagnosis Reference LY26-3961-1 © Copyright IBM Corp. 1980, 1987 


Restricted Materials of IBM 


Licensed Materials — Property of IBM 


DADSM Data Areas 


Buffer List 


CVAF Extent Table 


The following work areas and control blocks either are used only by the DADSM 
functions, or are mapped within DADSM work areas. 


Mapped by: ICVAFBFL macro. 
Chained from: Not applicable. 


Storage Location: Within the DADSM function work area and/or built 
dynamically by CVAF in subpool 229. 


Description: The buffer list in the DADSM work area is passed to CVAF through 
the CVAF parameter list in order to read and write VTOC DSCBs; it is supplied to 
the CVAFDIR macro BUFLIST keyword. The buffer lists, built dynamically by 
CVAF, contain the storage locations of the VTOC index space maps and the 
VTOC index entry records (VIERs). All DADSM functions, except ALLOC 
(CONV) and PRTCT, use the buffer list. 


Created when: The buffer list in the DADSM work area is created if DADSM 
needs to call CVAF to read or write a DSCB. The buffer lists built by CVAF are 
created when CVAF is called by DADSM to read the VTOC index space maps 
and/or search the VTOC index entry records. 


Released when: The buffer list in the DADSM work area is released when the 
DADSM work area is released. The buffer lists built by CVAF are released when 
DADSM calls CVAF and specify that the VTOC index entry records and/or the 
VTOC index space maps are to be released. The buffer lists are also released by 
DADSM recovery routines at abnormal termination processing. 


Mapped by: ICVARXNT macro. 
Chained from: Not applicable. 
Storage Location: Allocate, extend, scratch, and partial release work areas. 


Description: Used to represent allocated or released space extents when 
interfacing with CVAF. The information contained in the flags field is not used by 
CVAF, differs for each routine, and can be determined by examining the program 
listing. Used by the ALLOC (INIT), EXTND, SCRTCH, PRLSE, and VRF 
functions. 


The used-hole field is not used by CVAF, but is used by DADSM to contain the 
count of the number of format-1, format-2, format-3, format-5, and format-6 
DSCBs added to and removed from the VTOC during allocation or releasing space. 


Each extent entry contains two binary numbers: RTAI and RTA2. RTA1 is the 
relative track address of the first track of an extent area; RTA2 is the relative track 
address of the last track of the area, plus one. A relative track address is a binary 
number representing the displacement of the track from the first track of the 
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volume. For example, the relative track address of track 7 on cylinder 0 is 7. The 
relative track address of track 3 on cylinder 2 is 23 (if the volume has 10 tracks per 
cylinder). 


Created when: During ALLOC, EXTND, SCRTCH, PRLSE, and VRF function 
processing. 


Released when: Allocate, extend, scratch, partial release, or VRF work areas are 
released. 


Mapped by: ICVAFPL macro. 
Chained from: Not applicable. 
Storage Location: Within the DADSM function work area. 


Description: A parameter list supplied to CVAF. All functions, except ALLOC 
(CONV) and PRTCT, use the CVAF parameter list data area. 


Created when: By the DADSM function when CVAF is to be called. 


Released when: By the DADSM function when its work area is released. 


Mapped by: ICVVLSPC macro. 
Chained from: Not applicable. 
Storage Location: Allocate, extend, scratch, and partial release work areas. 


Description: Used to represent allocated or released space extents when 
interfacing with CVAF. The information contained in the flags field is not used by 
CVAF, differs for each routine, and can be determined by examining the program 
listing. Used by the ALLOC (INIT), EXTND, SCRTCH, PRLSE, and VRF 
functions. 


The used-hole field is not used by CVAF, but is used by DADSM to contain the 
count of the number of format-1, format-2, format-3, format-5, and format-6 
DSCBs added to and removed from the VTOC during allocation or releasing space. 


Each extent entry contains two binary numbers: RTA1 and RTA2. RTAI is the 
relative track address of the first track of an extent area; RTA2 is the relative track 
address of the last track of the area, plus one. A relative track address is a binary 
number representing the displacement of the track from the first track of the 
volume. For example, the relative track address of track 7 on cylinder 0 is 7. The 
relative track address of track 3 on cylinder 2 is 23 (if the volume has 10 tracks per 
cylinder). 


Created when: During ALLOC, EXTND, SCRTCH, PRLSE, and VRF function 
processing. 
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Released when: Allocate, extend, scratch, partial release, or VRF work areas are 
released. 


DADSM Preprocessing and Postprocessing Installation 
Exit Parameter List 
Mapped by: TECIEXPL macro. 
Chained from: Not applicable. 
Storage Location: Within DADSM function work area. Subpool 230 protect key 5. 


Description: The IEXPL contains data supplied to the DADSM preprocessing and 
postprocessing installation exits, IGGPREOO and IGGPOSTO. It also contains 
fields (IEXFMT1, IEXREASN), which are returned to DADSM allocate from the 
preprocessing exit, as well as a word (IEXRSVWD) which may be used by the 
preprocessing exit for passing data to the postprocessing exit. The DADSM 
functions ALLOC, EXTND, SCRTCH, PRLSE, and RNAME use IEXPL. 


Created when: The DADSM function is to give control to the preprocessing 
installation exit module, IGGPREOO. 


Released when: The DADSM function work area is freed. 
Data Set Control Blocks 
Mapped by: TECSDSL1 macro. 


Chained from: DSCBs reside in the VTOC. Format-1 DSCBs are not chained 
from any record in the VIOC. For an indexed VTOC, the VTOC index entry with 
the data set name of the format-1 DSCB contains the disk address (CCHHR) of 
the format-1 DSCB. Format-2 DSCBs are chained from the format-1 DSCB field, 
DS1PTRDS. Format-3 DSCBs are chained from the format-1 or -2 DSCB fields, 
DS1PTRDS or DS2PTRDS. The format-4 DSCB is the first record in the VTOC; 
the TTR of the format-4 DSCB is in the volume label of the volume and in the 
UCBVTOC field of the UCB. The first format-5 DSCB is the second record in the 
VTOC; subsequent format-5 DSCBs are chained from the previous format-5 
DSCB field, DSSPTRDS. The first format-6 DSCB is chained from the format-4 
DSCB field, DS4F6PTR; subsequent format-6 DSCBs are chained from the 
previous format-6 DSCB field, DS6PTRDS. 


Storage Location: Not applicable. 


Description: A format-1 DSCB describes a data set and the first three extents. A 
format-2 DSCB describes the structure of an ISAM data set. A format-3 DSCB 
describes the 4th through the 16th extent of a data set. Additional format-3 
DSCBs may be used to describe the 17th through the 123rd extent of a VSAM 
data set cataloged in an integrated catalog facility catalog. A format-4 DSCB 
describes the VTOC. A format-5 DSCB describes unallocated space on a volume 
which does not contain a VTOC index. A format-6 DSCB describes the extents 
shared by two or more data sets (split cylinder extents). A format-0 DSCB is an 
unused record in the VTOC. All DADSM functions use the data set control blocks 
(DSCBs). 
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Created when: The format-4 and the first format-5 DSCBs are created when the 
volume is initialized; for a nonindexed VTOC, subsequent format-5 DSCBs are 
created when the number of extents of unallocated space on the volume exceeds 26 
or a multiple of 26; for example, a third format-5 DSCB is created when the 
number of extents goes from 51 to 54 (exceeding 2 x 26). This can occur either 
during allocation or release of space on the volume. The format-1, -2, and perhaps 
format-3 DSCBs are created when the data set is allocated; the format-3 DSCB is 
created when a data set requires a 4th extent. The format-6 DSCB is created when 
the first split cylinder data set on the volume is allocated; subsequent format-6 
DSCBs are created when the number of split extents exceeds 26 or a multiple of 
26. This can happen only when a new split cylinder data set is allocated. 
Allocation of a split-cylinder data set is no longer supported by DADSM, but the 
existing split-cylinder data set can be scratched. A format-0 DSCB is created in all 
DSCBs, except the format-4 and first format-5 DSCB when the volume is 
initialized. A format-0 DSCB is also created when any other DSCB (except the 
first two DSCBs, the format-4 and first format-5 DSCB) is not needed. Format-0, 
-5, and -6 DSCBs are also created by the VTOC convert routine for an OS 
(nonindexed) VTOC. Format-0 DSCBs also are created by the VRF recovery 
routines for an indexed VTOC. 


Released when: A DSCB is released when a format-0 DSCB is written over it. 
The format-4 and first format-5 DSCBs are never released. The format-1 and -2 
DSCBs are released when the data set is deleted. The format-3 DSCB is released 
when the data set is deleted or when the partial release function (PRLSE) reduces 
the number of extents from four or more to three or less. A format-5 DSCB is 
released when the number of extents of unallocated space drops from above a 
multiple of 26 to below or equal to a multiple of 26; for example, the second 
format-5 is released when the number of extents of unallocated space goes from 27 
to 26. This can occur either during allocation or release of volume space on a 
nonindexed VTOC. A format-6 DSCB is released when the number of split 
cylinder extents drops to a multiple of 26 (for example, from 79 to 78); this 
happens only when a split-cylinder data set is deleted. 


Mapped by: TECDSECS macro. 
Chained from: Not applicable. 


Storage Location: The first 80 bytes of the initial work area obtained by the 
DADSM function. 


Description: Provides a register save area and the addresses of other data areas. 
All DADSM functions, except PRTCT, use the extended prefix. 


Created when: An extended prefix is obtained only with the initial work area 
obtained to process a DADSM request through the IECRES GET macro. 


Released when: The DADSM work area is freed using the IECRES FREE macro. 
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| Mapped by: LSPACE macro 
| Chained from: Register 1 on entry to IGCO007H. 
| Storage location: Caller’s work area. 
| Description: A parameter list used by the LSPACE function. 
| Created when:: By any caller of LSPACE. 
| Released when: Caller’s responsibility. 
LSPACE Work Area 
Mapped by: TECLSPWA macro. 
Chained from: Register 13 while LSPACE is in control. 
Storage Location: Subpool 230. 


Description: Used by the LSPACE function to read DSCBs from the VTOC of 
volumes for which space information is being gathered. 


Created when: During LSPACE initialization by IGC0007H. 

Released when: By LSPACE when LSPACE completes its function. 
Obtain Work Area 

Mapped by: TIECOBTWA macro. 

Chained from: Register 13. 

Storage Location: Subpool 230. 


Description: Used by the obtain function (OBTN) to read DSCBs from the 
VTOC. 


Created when: During obtain initialization (OBTN) by IGC0002G, which issues 
the IECRES GET macro. 


Released when: The DADSM work area is freed using the IECRES FREE macro. 
Partial Data Set Control Block 

Mapped by: TECPDSCB macro. 

Chained from: REALLOC parameter list. 

Storage Location: Caller’s work area. 


Description: A partial format-1 DSCB (the first 98 bytes) plus the primary space 
request in tracks and the number of directory blocks. 
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PARTREL Parameter List 
Mapped by: PARTREL macro. 
Chained from: Register 1 upon entry to IGGO20P0. 
Storage Location: Caller’s work area. 


Description: A parameter list used by the PARTREL partial release (PRLSE) 
function. 


Created when: By any authorized caller of partial release (PARTREL interface). 
Released when: Caller’s responsibility. 

PARTREL Partial Release Work Area 
Mapped by: A concatenation of IECDSECT, DCBD, and IEZDEB macros. 
Chained from: Register 11 or 13. 
Storage Location: Subpool 230. 
Description: A single getmain area which is subdivided to provide module 
IGG020P1 (DADSM partial release prior to PARTREL) a valid execution 


environment. 


Created when: By module IGGO20P0 during PARTREL partial release (PRLSE) 

initialization. 

Released when: By Module IGGO20P0 when the PRLSE function is finished. 
Password Data Set Record Format 

Chained from: Not applicable. 

Storage Location: The PASSWORD data set. 

Description: The PASSWORD data set contains records with a key length of 52 

bytes and a data length of 80 bytes. The first 44 bytes of the key are the data set 

name, left justified, and padded with blanks. The last 8 bytes of the key are the 

password for the data set. The first two bytes of the data are a binary counter, 

which is incremented when the data set is opened. The third byte of the data is a 


protection mode indicator set to one of four values: 


¢ X'QO!' to indicate that the password is a secondary password and the protected 
data set is to be read only 


¢ X'80' to indicate that the password is the control password and the protected 
data set is to be read only 


¢ X'O1' to indicate that the password is a secondary password and the protected 
data set is to be read and written 
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e X‘'81' to indicate that the password is the control password and the protected 
data set is to be read and written 


Created when: The protect SVC is called to create a new entry in the PASSWORD 
data set. 


Released when: The protect SVC is called to delete the entry in the PASSWORD 
data set. 


Prefix to DADSM Work Areas 
Mapped by: TECDSECS macro. 
Chained from: Prefix to DADSM work area. 


Storage Location: Precedes all work areas obtained by DADSM through the 
IECRES GET macro. 


Description: A prefix, included with each work area, used to chain the work areas 

together. All DADSM functions, except PRTCT, use the prefix to DADSM work 

areas. 

Created when: DADSM work areas are obtained using the IECRES GET macro. 

Released when: The DADSM work area is freed using the IECRES FREE macro. 
Protect Work Area 

Mapped by: IECDSECT macro. 


Chained from: Not chained from or related to the other DADSM work areas. 
Register 5 points to the protect work area, while protect is in control. 


Storage Location: Subpool 252. 


Description: Used by the PRTCT function to read from and write to the VTOC 
and the PASSWORD data set. 


Created when: During PRTCT initialization by module IGCOQOO9H. 

Released when: By module IGCO209H when the PRTCT function is finished. 
REALLOC Parameter List 

Mapped by: REALLOC macro. 


Chained from: Register 1 upon entry to ALLOCATE (SVC 32) when register 1’s 
high order bit is on. 


Storage Location: Caller’s work area. 


Description: A parameter list used by the allocate (ALLOC) function to process a 
partial DSCB that may require more than five extents for the 


Released when: Caller’s responsibility. 
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Recovery Routine Audit Trail 


Relinquish Parameter List 


Rename Work Area 


Mapped by: TECDSECS macro. 

Chained from: Not applicable. 

Storage Location: At the end of the first DADSM work area. 

Description: Used by O0/C/EOV-DADSM recovery routines in freeing resources 
allocated to a DADSM routine that has encountered an abnormal termination 
condition. This audit trail tells which resources to free. All DADSM functions, 
except PRTCT, use the audit trail area. 


Created when: Initial DADSM work area is obtained through the IECRES GET 
interface. 


Released when: The DADSM work area is freed. 


Mapped by: ICBAREL macro. 
Chained from: ARHDPTR in Scratch or Partial Release work area. 
Storage Location: Subpool 230. 


Description: A parameter list used by Scratch and Partial Release to pass 
information to MSS on virtual DASD space being released. 


Created when: Scratch or Partial Release determine the volume being processed is 
virtual DASD. 


Released when: Scratch or Partial Release work areas are released. 


Mapped by: TECRENWA macro. 

Chained from: Register 13. 

Storage Location: Subpool 230. 

Description: Used by the rename function (RNAMBE) to read and write DSCBs. 


Created when: During rename initialization (RNAME) by IGGDARO3, which 
issued the IECRES GET macro. 


Released when: When all the volume list entries have been processed. 


58 MVS/XA DADSM Diagnosis Reference LY26-3961-1 © Copyright IBM Corp. 1980, 1987 


Restricted Materials of IBM 


Licensed Materials — Property of IBM 


SAF Work Area and Parameter List 


Second Rename Work Area 


Transfer Control Table 


Mapped by: RACROUTE macro. 
Chained from: Not applicable. 


Storage Location: SAF work area and parameter list are processed in the DADSM 
work area. 


Description: The SAF work area is a 512-byte area used by SAF. The SAF 
parameter list is built at the time the RACROUTE macro is issued. It contains 
addresses to the data set name, the volume serial number, the SAF work area, and 
flags. 

Created when: Appears in the DADSM work area. 


Released when: At the completion of the DADSM function. 


Mapped by: TECRENWA macro. 

Chained from: SECWAPTR in IECRENWA. 

Storage Location: Subpool 230. 

Description: Used by rename (RNAME) to perform its function. 
Created when: During RNAME initialization by module IGC00030. 


Released when: When all the volume list entries have been processed by RNAME. 


Mapped by: XCTLTABL macro. 

Chained from: Not applicable. 

Storage Location: Within the module expanding the XCTLTABL macro. 
Description: The transfer control table is a list of module names and their entry 
point addresses (VCONS) that is used to transfer control (using the IECRES 
macro) among the DADSM modules and the close and EOV modules that give 


control to and receive control from the DADSM modules. All DADSM functions, 
except PRTCT, use the transfer control table. 


Created when: Appears at the end of each DADSM module as a result of the 
expansion of the XCTLTABL macro instruction. 


Released when: Not applicable. 
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VTOC Recording Facility (VRF) Data 
Mapped by: TECVRFDA macro. 
Chained from: Not applicable. 


Storage Location: VRF data is processed in the DADSM work area and is 
managed by CVAF in the VTOC index map (VIXM) in the VTOC index. 


Description: VRF data is used by DADSM to record sufficient information about a 
DADSM request to permit any partial updates to the VTOC and VTOC index to 
be either backed out or completed in the event the DADSM function is interrupted. 
The DADSM functions (ALLOC, EXTND, SCRTCH, PRLSE, and RNAME) and 
DFDSS (see DF DSS: Diagnosis Guide) use the VRF data. Since the VIXM 
contains space for several consecutive copies of VRF data, the VIXM will contain 
a recent history of the last VTOC updates made on the volume. 


Created when: VRF data is created in the DADSM work area as the DADSM 
function begins and before any VTOC or VTOC index updates have occurred. 
The VRF data is moved to the VIXM in virtual storage when DADSM calls the 
CVAFVRF ACCESS=WRITE macro supplying the VRF data. VRF data is 
written to the VTOC index and made active as the first WTOC or VTOC index 
update when DADSM calls the CVAFDIR macro to request that the VIXM 
containing active VRF data be written to the VTOC index. 


Released when: VRF data in the DADSM work area is released when the DADSM 
work area is released. Active VRF data in the VIXM is made inactive when 
DADSM has completed its VTOC updates. The CVAFVRF ACCESS=WRITE 
macro is called by DADSM, supplying no VRF data; this makes the VRF data in 
the VIXM in virtual storage inactive. The last update to the VTOC or VTOC 
index is to write all updated VTOC index entry records and VTOC index space 
maps to the VTOC index, specifying that the VIXM containing no active VRF data 
be the last record written to the VTOC index. 


WTG (Where-to-Go) Table 


Mapped by: Individual DADSM work areas. See description in Appendix A, 
“Data Area Layouts.” 


Chained from: Not applicable. 
Storage Location: Within the primary DADSM function’s work area. 


Description: Used in conjunction with the IECRES LOAD macro instruction to 
transfer control. All DADSM functions, except PRTCT, use the WTG table. 


Created when: DADSM work area acquired. 


Released when: DADSM work area released. 
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Data Area Linkages 


To facilitate getting and releasing work areas, the DADSM work areas are chained 
together through the work area prefix (IECPREFX). In most cases, to locate all 
the work areas of a DADSM function, you need only know the contents of the 
register pointing to the work area (usually register 11 or 13) at the time a DADSM 
routine is executing. Register 13 contains the address of the extended prefix of a 
DADSM work area during most DADSM processing. This address is preceded by 
the prefix that contains the address of subsequently obtained work areas associated 
with the DADSM request. Figure 14 on page 62 is an example that shows the 
work area chaining that results from the following conditions: (1) an allocation 
request (SVC 32) is issued, and (2) there is a device that has the RPS feature. 


Figure 15 on page 63 shows the linkages on a DASD volume between the VTOC 
and VTOC index. 
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ALWA 
RPSA 
EXWA 
LSWA 
OBWA 
PRWA 
PRW2 
REWA 
SCWA 
32DB 
CVWA 
CVWB 
AVWA 
EVWA 
SVWA 
PVWA 
RVWA 


«igure 14. 
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RPSA’ 


“ba| 


ALwa' 


t A (initial) 


T B (previous) 


24(18) 
t B (next) t A (next) 
28(1C) 
EXPR 
RPS 
Allocate Work Area 
Work Area 


LJ 


" Four-character identifiers that appear in the first four bytes of each prefix. The 
DADSM work area identifiers are: 


Allocate work area 

RPS work area 

Extend work area 

LSPACE work area 

Obtain work area 

Partial Release work area 

PARTREL Partia! Release work area 
Rename work area 

Scratch work area 

1GG032DB work area 

IGGVRFOO work area 

Area containing VRF data for |GGVRFOO 
IGGVRFO1 (Aliocate recovery) work area 
IGGVRFO2 (Extend recovery) work area 
IGGVRFOS3 (Scratch recovery) work area 
IGGVRFO4 (Partial Release recovery) work area 
IGGVRFOS (Rename recovery) work area 


Example of Data Area Linkage for an Allocation Request 
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11(B) 
VOLVTOC (10 bytes) 
CCHHR of VTOC 
(format-4 DSCB) 
VTOC index 
Z 
wa 
Cytinder 0 VPSM 
— vos 
a ee ed 


DSN CCHHR 


DSN CCHHR 


DSN CCHHR 


Record 1 | Record 2 | Record 3 a“ 
”” 


\ 


vVTOoc* 
index 


The data set name 
matches the data 
set name in the 
format-1 DSCB. 





format-4 | First OSCB OscB. | psce DSCB 


# 
VTOC Data Set osca format-5 | tormat-1 | format-1"] format-3 | format-1 
OSCB ~, 





“~,, ac, 
” 
” 
a \ 
”” 
Pe x‘ 
First format-S OSCB points to Data set name of VTOC index 
subsequent format-5 OSCBs is ‘SYS1.VTOCIX.nnn’ 


(for a nonindexed VTOC only). 


* Can be located anywhere on the volume 
after cylinder 0, track O. 


Figure 15. VTOC and VTOC Index Linkages 





LY26-3961-1 © Copyright IBM Corp. 1980, 1987 Data Area Linkages 63 


Restricted Materials of IBM 


Licensed Materials — Property of IBM 


Appendix A. Data Area Layouts 


For quick reference, the layout of the VTOC recording facility (VRF) data area is 
given in Figure 16. Any additional layouts of the data areas will be available on 
microfiche. The offsets of the where-to-go (WTG) table are provided in Figure 17 


on page 66. 
Offsets 

Dec. (Hex.) 
0 (0) 
0 (0) 
4 (4) 
6 (6) 

7 (7) 
8 (8) 
10 (A) 
11 (B) 
12 (C) 
56 (38) 
61 (3D) 
66 (42) 
66 (42) 


Figure 16 (Part 1 of 2). 
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Length Name 

Var. VRFDA 

4 VRFID 

2 VRFLENG 

1 VRFFCODE 

1 VRFFLAG 

| Bepere VRFNEXTD 

i nee VRFDSNEX 

re ae VRFISAME 

..1 1111 

2 VRFOFEXT 

1 

1 VRFPREXT 

44 VRFDSN 

5 VRFF1PTR 

5 VRFF2PTR 

0 VRFHEND 

5 VRFF3PTR 
VRF Data Area 


Description 


DADSM USE OF VTOC 
RECORDING FACILITY 
VRF ID IN EBCDIC 'VRF' 
LENGTH OF VRF DATA 
FUNCTION CODE 

VRF FLAG BYTE 

EXTEND ON NEW VOLUME 
ON = VRFNDSN EXISTS AT 
OFFSET VRFOFEXT OFF= 
VRFEXTBL EXISTS AT 
OFFSET VRFOFEXT 

ON = ISAM ALLOCATE 
WITH AN EXISTING F1 
DSCB. OFF= NOT ISAM 
ALLOCATE WITH AN 
EXISTING Fi DSCB. 
RESERVED 

OFFSET(nn) TO VRFEXTBL 
OR VRFNDSN IN VRF DATA 
RESERVED 

NUMBER OF PRIMARY 
EXTENTS 

DATA SET NAME 

CCHHR OF Fi DSCB 
CCHHR OF F2 DSCB (ISAM 
DS ONLY) 

END OF VRF DADA 
HEADER 

HEADER CCHHR OF F3 
DSCB(S) 
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Offsets 


Dec. 


71 


71 


nn 


nn+1 


nn+2 
nn+4 


Figure 16 (Part 2 of 2). 


(Hex.) 
(47) 


(47) 


(0) 
(1) 


(2) 
(4) 


Length Name 

5 VRFRSVD 

45 VRFRSVD 

44 VRFNDSN 

4 VRFEXTBL 

1 VRFEXFLG 

1 VRFEXCNT 

2 

Var. VRFEXENT 
VRF Data Area 
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Description 


RESERVED (EXTEND 
ONLY) 

UP TO NINE F3 CCHHRs, 
FOR A TOTAL OF 10 
(ALLOCATE ONLY) 

NEW DATA SET NAME (nn 
= VRFOFEXT IN VRF 
DATA) 

DADSM EXTENT TABLE (nn 
= VRFOFEXT IN VRF 
DATA) 

EXTENT TABLE FLAG 
BYTE 

NUMBER OF ENTRIES (mm) 
IN EXTENT TABLE 
RESERVED 

mm RTA1/RTA2 ENTRIES 


As shown in the figure below, the where-to-go (WTG) table is always located at 
offsets X'70' to X'7F' in the DADSM work area. It is used by macro IECRES to 


branch into or transfer control to other modules. 


Offsets 


Dec. 


112 


116 
124 


(Hex.) 


(70) 


(74) 
(7C) 


Length 
4 


8 


4 


Name 


WTGWTOPR 


WTO 


WTGMODNM 
WTGMODEP 


Description 


PREFIX FOR RES WTO 
IECWTGTB POINTS HERE 
MODULE NAME 
MODULE ENTRY POINT 
ADDRESS 


Figure 17. DADSM Where-to-Go (WTG) Table Definition 
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Appendix B. DADSM Return Codes 


Allocate Function 


Return 
Code 


0 (X'0') 


4 (X'4') 


8 (X'8') 


12 (X'C') 


16 (X'10') 
20 (X'14') 
24 (X'18') 
28 (X'1C') 
32 (X'20') 
36 (X'24') 
40 (X'28') 
44 (X'2C') 
48 (X'30') 
52 (X'34') 


56 (X'38') 


Explanation 


Successful allocation. 


Data set name requested already exists on volume; initial allocation 
not possible under the name given. 


No room available in VTOC or VTOC index. 


One of the following errors was encountered: 


e Permanent I/O error. 


e Error returned by CVAF. 


Requested absolute track not available. 


Requested quantity not available. 


Average record length greater than 65535 bytes. 


DSORG or DISP wrong in ISAM index request. 


No prime area request for ISAM data set. 


ISAM prime area must be requested before overflow. 


Space request must begin on cylinder boundary. 


ISAM DSNAME element duplication. 


Invalid REALLOC parameter list. 


Invalid JFCB or partial DSCB pointer. 


Directory space requested is larger than amount available on this 


volume. 
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60 (X'3C') 
64 (X'40') 
68 (X'44') 
72 (X'48') 


76 (X'4C') 


80 (X'50') 
84 (X'54') 
88 (X'58') 
92 (X'5C') 
96 (X'60') 
100 (X'64') 
104 (X'68') 


108 (X'6C') 


112 (X'70') 
116 (X'74') 


120 (X'78') 


124 (X'7C') 
128 (X'80') 
132 (X'84') 
136 (X'88') 
140 (X'8C') 


144 (X'90') 


148 (X'94') 
152 (X'98') 


156 (X'9C') 


Restricted Materials of IBM 
Licensed Materials — Property of IBM 
Nonindexed VTOC not supported for REALLOC ALLOC=ABS. 
Invalid user label request. 
Invalid UCB pointer. 
DOS VTOC cannot be converted to an OS VTOC. 


No space parameter given for new data set, or zero space requested 
at absolute track zero. 


Invalid request for ISAM index. 

ISAM multivolume index not allowed. 

ISAM DSNAME element invalid. 

ISAM multivolume overflow request not allowed. 
ABSTR AND CYL requests conflict. 

CYL and CONTIG requests conflict. 

Invalid space subparameter. 


Primary space request for an ISAM data set is zero, or primary space 
is zero for an ABSTR request. 


Index area request duplication. 
User labels not supported. 


Invalid combination of values for DSSIZE and minimum allocation 
unit. 


DSSIZE is not a multiple of the minimum allocation unit. 
Directory space request is larger than primary request. 
Space request must be ABSTR for DOS volume. 

Invalid F3 DSCB pointer. 

ISAM index must be requested before prime area. 


Last concatenated DD card unnecessary or invalid for this ISAM 
data set. 


Overlapping extents in VTOC. 
Overlapping DOS split cylinder extents in VTOC. 


DADSM allocation terminated because of possible VTOC error. 
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160 (X'AO') ISAM allocation terminated because of possible VTOC error. 
164 (X'A4') Allocation terminated because of DOS stacked pack format. 
168 (X'A8') RACF define failed; data set profile already defined. 
172 (X'AC') User not authorized to define data set. 


176 (X'BO') Installation exit rejected the request with a return code of 8; no 
further volume should be attempted. 


180 (X'B4') Installation exit rejected the request with a return code of 4. Fora 
nonspecific volume request; another volume may be attempted. 


184 (X'B8') RACF define with modeling specified and model not found. 


188 (X'BC') Invalid F2 DSCB pointer. 


Extend Function 


To EOV 
Return 
Code Explanation 
1 (X"1') Successful secondary allocation on the current volume. 
4 (X'4') Successful secondary allocation on the new volume. 


-1 (X'-1') — Error in secondary allocation on the current volume. 
— Fewer than three free VTOC records (format-0 DSCBs) 
— Quantity not available 


— Too many extents (more than 16) for the data set on this 
volume 
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Return 
Code Explanation 


-4 (X'-4') Error in secondary allocation on the new volume. 
— Duplicate name on the new volume 
— Fewer than three free VTOC records (format-0 DSCBs) 
— Quantity not available 


-8 (X'-8') Unable to convert VTOC to standard format, or a volume with the 
alternate tracks on cylinder 0 was encountered (DOS allocation). 


-12 (X'-C') Unable to define the new volume to RACF. 
-16 (X'-10') Permanent I/O error or unexpected CVAF error return code. 


-20 (X'-14') Installation rejected the request. 


To Integrated Catalog Facility/ VSAM Catalog Management 


Return 
Code Explanation 


161 (X'Al1') Return code for integrated catalog facility catalog caller. Successful 
secondary allocation on the current volume. 


129 (X'81') Return code for VSAM catalog caller. Successful secondary 
allocation on the current volume. 


-8 (X'-8') Unable to convert the VTOC to standard format. 
-16 (X'-10') Permanent I/O error or unexpected CVAF error return code. 
-20 (X'-14') Installation exit rejected the request. 


-129 (X'-81') Return code for VSAM catalog caller. Error in secondary allocation 
on the new volume. 


— Fewer than three free VTOC records (format-0 DSCBs) 
— Quantity not available 
— Too many extents for the data space on this volume 


-161 (X'-Al"') Return code for integrated catalog facility catalog caller. The 
reason is the same as that documented in -129 above. 
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To OS Catalog Management 
Return 
Code Explanation 
2 (X'2') Successful secondary allocation on the current volume. 


-2 (X'-2') Error in secondary allocation on the current volume. 
— Fewer than three free VTOC records (format-0 DSCBs) 
— Quantity not available 


— Too many extents (more than 16) for the data set on this 
volume 


-8 (X'-8') Unable to convert VTOC to standard format, or a volume with the 
alternate tracks on cylinder 0 was encountered (DOS allocation). 


-16 (X'-10') Permanent I/O error or unexpected CVAF error return code. 


-20 (X'-14') Installation rejected the request. 


LSPACE Function 


Return 
Code Explanation 


0 (X'0') Successful LSPACE processing. 


4 (X'4') I/O error while reading DSCBs or unexpected CVAF error return 
code. 


8 (X'8') Last allocation on this volume made under DOS, or a DADSM 
function has prematurely terminated and VTOC errors may exist. 


12 (X'C') | UCB address invalid. UCB not for direct access device. UCB 
not-ready bit is on, indicating device not ready; UCBVTOC=0, 
indicating volume not mounted. 


If a message area was specified, the reason associated with the return 
code is stored there. 


16 (X'10') Invalid message area address or SMF indicator. 
Figure 18 shows additional diagnostic information returned by LSPACE. This 


information is returned in Register 0, and, if the return code is not 16, in the 
LSPACE parameter list as well. 
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LSPAERCD | LSPASFID | LSPASFRT — | LSPASFRS_| Description 


12 (0C) 


Z 
~~ 
> 


Not authorized for SMF 


12 00) Bad FMT Ara storage Key 


12 (0C) 


12 (00) 
12 (0C) 


12 (0C) ENO RETC N/A 


N/A 
04 (04) ECB STAT 
04 (04) ECB STAT N/A 
04 (04) ECB STAT N/A 


UCB not found 
UCB VTOC pointer is zero 


N/A 


12 (OC) xr N/A sd X08" UCB not direct access device 


Invalid UCB status 
Failed ENQ on SYSZDMNT 


F5’s are invalid 


N/A 
N/A Error reading F4 & F5 
Error reading next F5 


Error reading volume label 


04 (04) Error getting F4/Space maps 
04 (04) Error getting free extents 

04 (04) Error getting FO count 

04 (04) /x'g3t = |DSMRETC —[CVSTAT | Error getting VIR count 


04 (04) VRF RETC CVSTAT Error checking for VRF 


00 (00 No problems 


Figure 18. DADSM LSPACE Diagnostic Information 


Abbreviation 
LSPAERCD 
LSPASFID 
LSPASFRT 
LSPASFRS 
N/A 
CVSTAT 
ENQ RETC 
DIR RETC 
DSM RETC 
VRF RETC 
ECB STAT 


72 MVS/XA DADSM Diagnosis Reference 


Meaning 

Return code 

Subfunction identifier 
Subfunction return code 
Subfunction reason code 

Not Applicable 

CVSTAT field of CVAF parameter list 
Return code from ENQ 
Return code from CVAFDIR 
Return code from CVAFDSM 
Return code from CVAFVRF 
ECB completion code 
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Obtain Function 
Return 
Code Explanation 
0 (X'0') Successful completion of Obtain routine. 
4 (X'4') The required volume was not mounted. 


8 (X'8') The F1 DSCB was not found in the VTOC of the specified volume. 

12 (X'C') | A permanent I/O error or an invalid F1 or F4 DSCB was 
encountered when processing the specified volume or an unexpected 
CVAF error return code was encountered. 


16 (X'10') The pointer to the work area passed by the caller was invalid. 


20 ('14') The absolute address passed (seek option) was not with the 


boundaries of the VTOC. 
Partial Release Function 
Return 
Code Explanation 
0 (X'0') The requested partial release was successful. 


2 (X'2') Unable to find extent in F1 DSCB. 

4 (X'4') Unable to find extent in F3 DSCB. 

8 (X'8') Another DCB is open to the data set. 

12 (X'C') Invalid parameter list. 

16 (X'10') A permanent I/O error was encountered during processing, or an 
unexpected CVAF error return code was encountered, or the 
installation exit rejected the request, or an I/O error occurred while 
tracks to be released were being erased. 

20 (X'14') DSN, or DSN pointer is invalid. 

24 (X'18') Invalid UCB pointer. 

28 (X'1C') Given DSORG is not supported. 


32 (X'20') Nospace in VTOC. 
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Protect Function 


Return 
Code 


0 (X'0') 


4 (X'4') 


8 (X'8') 


12 (X'C') 

16 (X'10') 
20 (X'14') 
24 (X'18')! 
28 (X'1C') 


32 (X'20')2 


36 (X'24')2 
40 (X'28')2 
44 (X'2C') 
48 (X'30')2 
52 (X'34')2 
56 (X'38"')2 


Notes: 
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Explanation 
The PASSWORD data set was successfully updated. 


The password of the data set name was already in the PASSWORD 
data set. 


The password of the data set name was not in the PASSWORD data 
set. 


A control password is required or the one supplied is incorrect. 
The supplied parameter list was incomplete or incorrect. 

There was an I/O error in the password data set. 

The PASSWORD data set was full. 

The validity check of the buffer address failed. 


The LOCATE macro failed. LOCATE’s return code is in register 1 
and the number of indexes searched is in register 0. 


The OBTAIN macro failed. OBTAIN’s return code is in register 1. 
The DSCB could not be updated. | 

The PASSWORD data set does not exist. 

Tape data set cannot be protected. 

Data set in use. 


The data set uses the virtual storage access method (VSAM). 


I For this return code, a message is written to the console, indicating that the 
PASSWORD data set is full. 


2 For these return codes, the PASSWORD data set has been updated, but the 
DSCB has not been flagged to indicate the protected status of the data set. 
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Rename Function 


Return 

Code Explanation 

0 (X'0') Successful completion. 

4 (X'4") No volumes containing any part of the data set were mounted, nor 
did register 0 contain the address of a unit that was available for 
mounting a volume of the data set to be renamed (this completion 
code is accompanied by a setting of 5 in the rename status code of 
-each entry of the volume list). 

8 (X'8') An unusual condition was encountered on one or more of the 
volumes. 

12 (X'C') The volume list passed to rename was not valid (this return code is 


not accompanied by the setting of a rename status code in the 
volume list). 


After the RENAME macro instruction is executed, the last byte of each 12-byte 
entry in the volume list indicates the following conditions: 


RENAME 

Status 

Code Explanation 

0 (X'0') The F1 DSCB for the data set has been renamed in the VTOC on 
this volume. 

1 (X'1') The VTOC of this volume does not contain the F1 DSCB of the data 
set to be renamed. 

2 (X'2') The data set could not be renamed because the data set was 
password protected and the password was not supplied in the two 
attempts allowed, or an attempt was made to rename a VSAM data 
space, or an attempt was made to rename a VTOC index data set. 

3 (X'3') An F1 DSCB containing the new data set name already exists in the 
VTOC of this volume, or an attempt was made to rename a data set 
to a name starting with 'SYS1.VTOCIX'. 

4 (X'4') A permanent I/O error or an invalid F1 DSCB was encountered 
while trying to rename the data set on this volume, or there is no 
space in the index VIER for the new name, and no additional VIERs 
are available. 

5 (X'5§') It could not be verified that this volume was mounted nor was there a 
unit available for mounting the volume. 

6 (X'6') The operator was unable to mount this volume. If the volume is an 
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MSS virtual volume and is running in a JES3 environment, JES3 
would not allow the volume to be mounted. 
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Scratch Function 


7 (X'7') 


8 (X'8') 


Return 
Code 


0 (X'0") 
4 (X'4') 


8 (X'8') 


12 (X'C') 
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The data set was not renamed because it was currently open for 
processing. 


The data set is defined to RACF, but either the accessor is not alter 
authorized to the data set or the data set is defined to RACF on 
multiple volumes. 


Explanation 
Successful scratch 


No volumes containing any part of the data set were mounted, nor 
did register 0 contain the address of a unit that was available for 
mounting a volume of the data set to be scratched. (This return code 
is accompanied by the setting of status code 5 in all entries of the 
volume list.) 


An unusual condition was encountered on one or more volumes This 
return code is not accompanied by the setting of a status code. 


Issued for one of the following reasons: 


Invalid parameter list address. 

Invalid volume list address. 

Invalid volume count. 

Conflicting options (both ERASE and NOERASE) were found 
in the parameter list. 


After the SCRATCH macro instruction is executed, the last byte of each 12-byte 
entry in the volume list indicates the following conditions: 


Scratch 
Status 
Code 


0 (X'0') 


1 (X'1") 


2 (X'2') 


3 (X'3') 
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Explanation 


The DSCB for the data set has been deleted from the VTOC on the 
volume pointed to. 


The VTOC of this volume does not contain the DSCB to be deleted. 
The macro instruction failed when the correct password was not 
supplied by the console operator or TSO terminal operator in the two 
attempts allowed, or the user tried to scratch a VSAM data space or 
a VTOC index data set. 


The DSCB was not deleted because either the OVRD option was not 
specified or the retention cycle had not expired. 
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Scratch 
Status 
Code Explanation 


4 (X'4') A permanent I/O error on an invalid F1 DSCB was encountered 
when processing this volume; or an unexpected CVAF error return 
code was encountered; or the installation exit rejected the request; or 
an I/O error occurred while the DASD tracks occupied by the data 
set were being erased when the ERASE option was specified in the 
scratch parameter list or when the ERASE attribute was specified for 
a RACF-defined data set. 


5 (X'5') It could not be verified that this volume was mounted, nor was there 
a unit available for mounting the volume. If one or more of the 
volumes was an MSS mass-storage volume, see the explanation of 
message IEC666I in System Messages. 


6 (X'6') The operator was uuable to mount this volume. If this volume is an 
MSS virtual volume and is running in a JES3 environment, JES3 
would not allow the volume to be mounted. 

7 (X'7') The DSCB was not deleted because the data set was open. 

8 (X'8') The DSCB indicates the data set is defined to RACF but either the 


accessor is not authorized to the data set or to the volume, or the 
data set is a VSAM data space. 
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List of Abbreviations 

BPAM Basic Partitioned Access Method 

CVAF Common VTOC Access Facility 

CVPL CVAF parameter list 

DADSM Direct Access Device Space 
Management 

DCB Data control block 

DEB Data extent block 

DFDSS Data Facility Data Set Services 

DIRF DADSM interrupt-recording 
facility 

DOS Disk Operating System 

DSAB Data set association block 

DSCB Data set control block 

EOV End of volume 

GTF Generalized Trace Facility 

ICKDSF Device Support Facility 

ISAM Indexed Sequential Access Method 

JFCB Job file control block 

MSS Mass storage system 

PDSCB Partial data set control block 
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RACF 
RBA 
R/T 
SAF 
SMF 
SVC 


SVRB 


UCB 
VDSCB 
VIER 


VIO 


VMDS 
VPSM 
VRF 

VSAM 


VTOC 


Resource Access Control Facility 
Relative byte address 
Recovery termination manager 
System Authorization Facility 
System management facilities 
Supervisor call instruction 
Supervisor request block 
Track, track record 

Unit control block 

Virtual data set control block 
VTOC index entry record 
Virtual I/O 

VTOC index map 

VTOC map of DSCBs 

Volume pack space map 
VTOC recording facility 
Virtual Storage Access Method 
Volume table of contents 


Where-to-go 
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